Summary

Introduces a unified preference system that persists UI state (theme, sidebar, column visibility, ordering, filters, custom keys) through a pluggable adapter layer. Preferences are server-rendered from the adapter on every page load — no flicker on first paint, no round-trip before the UI reflects saved state.

Out of the box everything lives in the Phoenix session (zero config). Route any prefix to a per-user database in config:

config :backpex, Backpex.Preferences,
  adapters: [
    {"global.*",   Backpex.Preferences.Adapters.Session, []},
    {"resource.*", MyApp.Preferences.EctoAdapter, repo: MyApp.Repo},
    {:default,     Backpex.Preferences.Adapters.Session, []}
  ],
  identity: {MyAppWeb.PreferencesIdentity, :resolve, []}

Architecture

Core modules

Dispatcher API (Backpex.Preferences)

• get/3 — read, fall back to :default. Accepts a %Context{} or a bare session map. Logs a warning when an adapter returns an unexpected error.
• fetch/3 — like get/3 but returns {:ok, value} | :error | {:error, reason}. Distinguishes "not found" (including :unidentified) from adapter failure. Use this when deciding whether to apply a default — %{}/[] can be an explicit user choice (e.g. "clear all filters") and must not be overwritten.
• get_map/3 — read a prefix as a nested map.
• put/4 — write from a socket or conn; falls back to push_event/3 when the adapter can't write from a LiveView context.
• put_batch/3 — cross-adapter batch writes, best-effort, first-error-wins. On the first adapter error the batch short-circuits and returns {:error, {key, reason}}. Earlier writes may have already committed — callers should treat partial success as possible. Each entry passes through the configured validate_keys strategy (same as put/4), and adapter exceptions surface as {:error, {key, {:exception, reason}}} rather than crashing the caller.
• subscribe/1 / unsubscribe/1 — opt-in Phoenix.PubSub subscriptions for the current user's preference changes (see "Cross-tab sync" below).

Router pattern types

• Exact string ("global.theme") and trailing-wildcard ("resource.*") — longest-prefix-first precedence.
• :default — catch-all fallback.
• 1-arity match function (&String.ends_with?(&1, ":columns")) — escape hatch for cross-cutting carve-outs. Ranks most-specific (always beats string patterns); first-in-config-order wins among matches; excluded from resolve_prefix/2 since a function cannot cleanly own a subtree.

Identity resolution

One MFA in config (identity: {Mod, :fun, []}); the dispatcher calls the resolver on every dispatch and caches the result on ctx.identity for the duration of that single call, so each adapter invocation sees a consistent value. The resolver receives a %Backpex.Preferences.Context{} — read ctx.assigns.current_scope first (freshest, post-auth), fall back to ctx.session only for edge cases. If memoization across calls matters, the application should cache externally (e.g. via on_mount assign). Keep the resolver cheap.

Key validation (opt-in)

Backpex.Preferences.Key.validate/1 checks a key against known top-level prefixes (global, resource, custom, plus anything an app registers via config :backpex, Backpex.Preferences.Key, extra_prefixes: […]). Wire validation into the dispatcher with config :backpex, Backpex.Preferences, validate_keys: :log | true:

• Default (off): zero cost; nothing logs.
• :log (recommended for dev): Logger.warning on unknown-prefix / empty / malformed keys; dispatch still proceeds.
• true (recommended for test): raises ArgumentError so CI catches typos mechanically.

The built-in Keys helpers self-check at compile time that every canonical key passes validate/1.

Cross-tab sync (opt-in PubSub)

Every successful put/4 and every successful entry in put_batch/3 broadcasts {:backpex_preference_changed, %{key, value, source: :controller | :server}} on "<topic_prefix>:<identity>" when configured:

config :backpex, Backpex.Preferences,
  pubsub: [server: MyApp.PubSub, topic_prefix: "backpex_preferences"]

Default config emits nothing — zero cost. Broadcast failures (misconfigured server, etc.) are caught, logged, and never break the write. Topics are keyed per-identity. Anonymous callers (nil/:unidentified) are not broadcast and subscribe/1 is a no-op for them, to prevent cross-user fan-out on the shared anonymous topic. LiveViews subscribe with Backpex.Preferences.subscribe(current_user.id) and handle {:backpex_preference_changed, _} in handle_info/2.

Opt-in persistence for index state

New persist: option on use Backpex.LiveResource:

use Backpex.LiveResource,
  adapter_config: [...],
  persist: [:order, :filters, :columns]

• :order — reads resource:<Mod>:order on mount; writes on handle_params when order changes.
• :filters — reads resource:<Mod>:filters on mount; writes on handle_params when filters change.
• :columns — reads resource:<Mod>:columns on mount; writes on the toggle_column event.

Default is []: the URL is the source of truth for order and filters, and column state lives in-memory.

Built-in key reference

Key encoding

Keys whose segments contain dots (typically because a segment embeds a module name like MyApp.MyLive) use : as the separator: resource:MyApp.MyLive:columns parses into three clean segments. Keys without embedded module names use the usual dot form: global.theme.

Integration contracts

Spelled out under "Contracts" in the guide. The two that bite hardest:

• Attach Backpex.InitAssigns AFTER your auth on_mount hook. The Context built at mount carries socket.assigns, so identity resolvers can read current_scope directly instead of re-implementing the app's session-token lookup.

• Preserve the preferences session key across renew_session/2. Use Backpex.Preferences.Session.preserve/1 + restore/2:

  def renew_session(conn, _user) do
    backpex_prefs = Backpex.Preferences.Session.preserve(conn)
  
    conn
    |> configure_session(renew: true)
    |> clear_session()
    |> then(&Backpex.Preferences.Session.restore(&1, backpex_prefs))
  end

Breaking changes (v0.19 overhaul)

Spelled out in full in guides/upgrading/v0.19.md:

• Backpex.ThemeSelectorPlug removed — theme is populated by Backpex.InitAssigns.
• Root layout uses @current_theme instead of @theme.
• theme_selector component takes current_theme.
• app_shell component takes sidebar_open.
• BackpexSidebar hook replaces BackpexSidebarSections.

With no :backpex, Backpex.Preferences config, every key routes to the Session adapter — this matches the zero-config default and keeps behavior stable for apps that don't opt into a custom adapter.

Migration — opting into a DB-backed adapter

1. Implement Backpex.Preferences.Adapter against your table (two complete recipes in the guide).
2. Add an identity resolver MFA. Read ctx.assigns.current_scope first.
3. Add one config block:

   config :backpex, Backpex.Preferences,
     adapters: [
       {"resource.*", MyApp.Preferences.EctoAdapter, repo: MyApp.Repo},
       {:default, Backpex.Preferences.Adapters.Session, []}
     ],
     identity: {MyAppWeb.PreferencesIdentity, :resolve, []}

4. Opt in per resource:

   persist: [:order, :filters, :columns]

5. If your app uses UserAuth.renew_session/2, add the Backpex.Preferences.Session.preserve/restore pair (see above).

JavaScript API

The compiled bundle exports BackpexPreferences as a named export alongside Hooks:

import { BackpexPreferences } from "backpex"

// Fire-and-forget HTTP POST; default behavior for server-synced writes.
BackpexPreferences.set("custom.my_setting", { foo: "bar" })

// Read a namespaced sessionStorage mirror, falling back when absent/unavailable.
// Type of the fallback drives deserialization (boolean, number, string, JSON).
const open = BackpexPreferences.get("global.sidebar_open", true)

// Write both sessionStorage (synchronous, survives live_redirect) and the
// server. Use for UI chrome whose server-rendered default is read at mount.
BackpexPreferences.set("global.sidebar_open", false, { mirror: "session" })

Mirror keys are namespaced under backpex.prefs.* in sessionStorage. The mirror is per-tab (by design) — for cross-tab consistency, use the PubSub cross-tab sync on the server side. Built-in _sidebar.js hook uses mirror: 'session'; _theme_selector.js intentionally does not (theme UI lives outside the LiveView tree).

Writes that can't be persisted from a LiveView context (for example put/4 called on a socket when the adapter needs to set a session cookie) fall back to a push_event/3 with the backpex:set_preference name; the hook in assets/js/hooks/_preferences.js forwards them to POST /backpex_preferences.

Observability

Every error path in the dispatcher logs a Logger.warning with the adapter module, key, and reason. Rescue points in the identity resolver log the resolver MFA. No telemetry events yet — surface can be added in a follow-up if operators need structured metrics.

Testing

mix lint: credo clean, mix format --check-formatted clean, mix compile --warnings-as-errors clean.

End-to-end LiveView integration coverage for persist: [:order, :filters, :columns] lives at demo/test/demo_web/live/preferences_persistence_test.exs. Mounts DemoWeb.PostLive, triggers sort / filter / column-toggle interactions, and asserts the matching push_event fires with the canonical key — the emitter and the test pull from the same Backpex.Preferences.Keys and Backpex.Preferences.LiveView.event_name/0.

Downstream apps writing their own ExUnit tests can import Backpex.Test to get live_resource_index/3 (follows the default-filter redirect transparently) and put_preference/3 (seed a preference into the conn before mount).

Test plan

Session-adapter preferences (default config):

• Toggle the sidebar open/closed → reload → state persists.
• Toggle the sidebar, then click an internal live_redirect link → sidebar stays as the user left it (no snap-back to the stale session snapshot — sessionStorage mirror covers this).
• Switch the theme via the theme selector → reload → <html data-theme> reflects the choice.
• Expand/collapse a sidebar section → reload → section state persists.
• Expand/collapse a sidebar section, then live_redirect to another resource → section stays as the user left it.
• Each write produces a POST /backpex_preferences returning {ok: true}.

Opt-in persist: on a demo LiveResource (e.g. DemoWeb.PostLive at /admin/posts):

• DemoWeb.PostLive is already configured with persist: [:order, :filters, :columns].
• Sort by a column → reload at the base URL (no query params) → sort is restored.
• Apply a filter → reload at the base URL → filter is restored.
• Clear all filters explicitly → reload at the base URL → filters stay cleared (not overwritten by :default filters).
• Toggle column visibility → reload → hidden columns remain hidden.
• On a resource without persist:, the same actions reset on reload (proves the flag gates persistence).

Cross-adapter routing:

• Configure resource.* to an ETS-backed test adapter; re-run the opt-in checks; writes land in ETS and the session cookie stays empty for resource keys.
• Configure a match-function route (e.g. {fn k -> String.ends_with?(k, \":columns\") end, SessionAdapter, []}) above {\"resource.*\", EctoAdapter, ...} → :columns writes land in the session, :order/:filters writes land in Ecto.

Session-renewal preservation:

• App using Backpex.Preferences.Session.preserve/restore in UserAuth.renew_session/2 — log in, toggle theme, log out, log back in → theme preserved (session-backed prefs survive the renewal).

Identity resolver:

• Resolver that reads ctx.assigns.current_scope.user.id works when Backpex.InitAssigns is attached after the app's auth on_mount hook — writes route correctly to the per-user adapter row.
• Resolver receives :unidentified (via ctx.assigns being empty) when called from an anonymous controller context — reads return :default, writes return {ok: false, error: %{reason: :unidentified}}.

Key validation (opt-in):

• With config :backpex, Backpex.Preferences, validate_keys: :log set in config/dev.exs, calling Backpex.Preferences.get(session, \"globl.theme\") logs a warning naming the unknown-prefix key; the call still returns the default.
• With validate_keys: true in config/test.exs, the same call raises ArgumentError naming the offending key and listing known_prefixes/0.

Cross-tab sync (opt-in PubSub):

• With pubsub: [server: MyApp.PubSub] configured, open two browser tabs as the same user; toggle theme in tab A; tab B's LiveView.handle_info/2 receives {:backpex_preference_changed, %{key: \"global.theme\", value: new_theme, source: :controller}}.
• Misconfigure the server name (e.g. atom not matching any running PubSub); toggle theme → write still succeeds, Logger.warning logged, no crash.
• Batch write that halts on entry N → entries 0..N-1 broadcast, entry N+ do not.

Error paths:

• Unauthenticated user hits a write routed to a DB adapter → response is 200 {ok: false, error: %{key: _, reason: :unidentified}}, no exception.
• Batch write where one adapter errors → HTTP 422 with {ok: false, error: %{key, reason}}; subsequent entries in the batch are short-circuited (not dispatched). Earlier successful entries may already be committed.
• Adapter stubbed to raise on put → Logger.warning captured; response is {ok: false, error: %{reason: {:exception, _}}}.

Stacked on

Stacked on top of PR #1748 (feature/collapsible-sidebar). Retargets to develop once that merges.